/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/
/* 
This file is the header for the Bmp24LineReader Module. This Module allows
loading an image from a color bitmap file in 24-bits-per-pixel format. The 
Image is loaded row by row, starting from the top row.

Example Usage:
-------------

	// for simplicity, this example skips some failure checks

	int Pitch;
	Byte_t* LineBuffer = NULL;

	Bmp24LineReader Reader = OpenBmp24LineReader( "Pic.bmp" );

	if ( !IsInitialized( Reader ) ) { printf("error!\n"); exit(1) }

	Pitch = GetPitch( Reader );

	Linebuffer = (Byte_t*)malloc( Pitch * sizeof(Byte_t) );
	// check success of allocation here 

	Res = ReadRow( Reader, LineBuffer );
	// LineBuffer now contains the TOP row of the image (if ReadRow succeeded)
	
	DoSomethingWith( LineBuffer);

	Res = ReadRow( Reader, LineBuffer );
	// LineBuffer now contains the SECOND row from the top (if ReadRow succeeded)

	DoSomethingWith( LineBuffer);

	CloseBmp24LineReader( &Reader );

This File was written as part of HW assignment 3 in the course "Introduction
To Systems Programming" at Tel-Aviv University's School of Electrical 
Engineering, Winter 2012, by Amnon Drory. 
*/ 
/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/

#ifndef __BITMAP_LINE_READER_H
#define __BITMAP_LINE_READER_H

/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/

#include "Hw3Types.h"

/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/

/*=======*/
/* Types */
/*=======*/

typedef void* Bmp24LineReader;

typedef enum { SUCCESS, FAILURE, END_OF_FILE } EReadRowRes;

/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/

/*=======================*/
/* Function Declarations */
/*=======================*/

/**
 * OpenBmp24LineReader() creates a 'Bmp24LineReader' and opens 
 * the bitmap file for reading. 
 * 
 * accepts:
 * -------
 * Filename - the name of the bitmap file to read. It must be a file in 
 * 24 bits per pixel bitmap format.
 *
 * Returns:
 * -------
 * a new Bmp24LineReader object. If this function failed, then calling
 * IsInitialized() on the created reader will return FALSE.
 */ 
Bmp24LineReader OpenBmp24LineReader( const char* Filename );

/**
 * IsInitialized() checks if a reader object has been successfully 
 * initialized by OpenBmp24LineReader().
 * 
 * accepts:
 * -------
 * Reader - the Line Reader to check.
 *
 * Returns:
 * -------
 * TRUE - if Reader is initialized.
 * FALSE - otherwise.
 */ 
BOOL IsInitialized( Bmp24LineReader Reader);

/**
 * ReadRow() reads the current row of a bitmap image into a buffer.
 * The first time that this function is called, it will read read the 
 * top row of the image. The next time, it will read the 2nd row from
 * the top, and so on untill the bottom of the image. 
 *
 * Format of an image line:
 * ------------------------
 * each pixel of a bitmap image in 24-bits-per-pixel format is represented as three
 * consecutive bytes, representing the Blue, Green, and Red elements of its color.
 * the data for a row of pixels is stored from left to right, as follows:
 *		Blue0, Green0, Red0, Blue1, Green1, Red1, Blue2, Green2, Red2, ...
 * The total length of the row must be divisible by four, so several bytes of 
 * padding may be added at the end of the row. For example, a row with two pixels:
 *		Blue0, Green0, Red0, Blue1, Green1, Red1, Padding, Padding
 * The Pitch of the image is the length of a row in bytes. 
 * In the two-pixel example above, the Pitch is 8. 
 * 
 * accepts:
 * -------
 * Reader - the Line Reader object. 
 * Destination - the memory location into which to load the current row. To contain
 * the loaded row, this memory should by an array af atleast Pitch bytes (see GetPitch() ).
 *
 * Returns:
 * -------
 * SUCCESS - of the row was loaded successfully
 * END_OF_FILE - if row was not loaded because all the rows of the image have already 
 *               been loaded by previous calls to this function.
 * FAILURE - otherwise
 */ 
EReadRowRes ReadRow( 
	Bmp24LineReader Reader, 
	Byte_t* Destination );

/**
 * Closes the bitmap file and releases all memory asociated with the Line Reader.
 *
 * accepts
 * -------
 * ReaderPtr - The address of the Line Reader ( = a pointer to the Line Reader ).
 *             A pointer is passed and not the Reader itself, to allow this function
 *			   to make the Reader invalid, therefore preventing using it by error after
 *             it has been closed.
 */
BOOL CloseBmp24LineReader( Bmp24LineReader *ReaderPtr );

/**
 * GetPitch returns the Pitch of the image, which is the length of a 
 * row in bytes. This is different from the Width of an image, which is the 
 * length of a row in _pixels_ . for example, an image with a width of 3 has a pitch of 12, 
 * as the bytes in the row are as as follows:
 *  Blue0, Green0, Red0, Blue1, Green1, Red1, Blue2, Green2, Red2, padding, padding, padding
 *
 * See the documentation of ReadRow() above for more on the Bmp24 format.
 *
 * accepts:
 * -------
 * Reader - the Line Reader object. 
 *
 * returns:
 * -------
 * the Pitch of the image. On failure, returns 0.
 */ 
int GetPitch( Bmp24LineReader Reader );

/**
 * GetHeight()
 * 
 * accepts:
 * -------
 * Reader - the Line Reader object. 
 *
 * returns:
 * -------
 * the Height of the image in pixels. On failure, returns 0.
 */ 
int GetHeight( Bmp24LineReader Reader );

/**
 * GetWidth()
 * 
 * accepts:
 * -------
 * Reader - the Line Reader object. 
 *
 * returns:
 * -------
 * the Width of the image in pixels. On failure, returns 0.
 */
int GetWidth( Bmp24LineReader Reader );

/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/

#endif // __BITMAP_LINE_READER_H